home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / NDK / NDK_3.5 / Documentation / Autodocs / button_gc.doc < prev    next >
Encoding:
Text File  |  1999-10-29  |  12.2 KB  |  373 lines
  1. TABLE OF CONTENTS
  2.  
  3. button_gc/--datasheet--
  4. button_gc/BUTTON_GetClass
  5. button_gc/--datasheet--                               button_gc/--datasheet--
  6.  
  7.     NAME
  8.         button_gc -- create button BOOPSI objects
  9.  
  10.     SUPERCLASS
  11.         gadgetclass
  12.  
  13.     REQUIRES
  14.         bevel.image, glyph.image
  15.  
  16.     DESCRIPTION
  17.         The button gadget class is used to create action buttons that are
  18.         momentary, toggle and sticky.  This class also supports relativity
  19.         and placement within the window border.
  20.  
  21.         Advantages that this class provides:
  22.  
  23.          > Centered images.
  24.  
  25.          > Centered pen-sensitive glyphs.
  26.  
  27.          > Multi-frame images animation ability (NEW V42)
  28.  
  29.          > Ability to change the text and background colors for normal
  30.            and selected buttons.
  31.  
  32.          > Supports window relativity.
  33.  
  34.          > Supports OS 3.0 BOOPSI Gadget HelpTest.
  35.  
  36.      METHODS
  37.         OM_NEW -- Passed to superclass, defaults set, then OM_SET.
  38.  
  39.         OM_SET -- Passed to superclass, custom tags set.
  40.  
  41.         OM_GET -- Custom tag returned or passed to superclass.
  42.  
  43.         OM_UPDATE -- Passed to superclass, options set then rendered.
  44.  
  45.         OM_NOTIFY -- Tag set then passed to superclass.
  46.  
  47.         OM_DISPOSE -- MemPool memory freed, then Passed to superclass.
  48.  
  49.         GM_RENDER -- Passed to superclass, then button is rendered.
  50.  
  51.         GM_HITTEST -- Overrides supperclass, returns GMR_HITTEST.
  52.  
  53.         GM_GOACTIVE -- Passed to superclass, button activated.
  54.  
  55.         GM_HANDLEINPUT -- Overrides supperclass, all input processed.
  56.  
  57.         GM_GOINACTIVE -- Passed to superclass, button deactivated.
  58.  
  59.         GM_DOMAIN -- Returns GDOMAIN_MINIMUM and GDOMAIN_MAXIMUM dimensions.
  60.  
  61.         GM_KEYACTIVE -- Private method for keyboard control.
  62.  
  63.         GM_KEYINACTIVE -- Private method for keyboard control.
  64.  
  65.      ATTRIBUTES
  66.  
  67.         GA_ID (WORD)
  68.  
  69.             Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET, OM_NOTIFY)
  70.  
  71.         GA_Selected (BOOL)
  72.             Determines whether the button is selected or not.
  73.             Changing selection state will invoke GM_RENDER.
  74.  
  75.             Defaults to FALSE.
  76.  
  77.             Applicability is (OM_NEW, OM_SET, OM_GET, OM_NOTIFY)
  78.  
  79.         GA_Disabled (BOOL)
  80.             Determines whether the button is disabled or
  81.             not.  Changing disable state will invoke GM_RENDER.  A disabled
  82.             button's border and label are all rendered in SHADOWPEN and then
  83.             dusted in a ghosting pattern.
  84.  
  85.             Defaults to FALSE.
  86.  
  87.             Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET,  OM_NOTIFY)
  88.  
  89.         GA_Text (STRPTR)
  90.             Used to specify the NULL terminated string to use as the text 
  91.             for the gadget.  The Text() function is used to draw the text.
  92.             NULL is valid input. Changing the label will invoke GM_RENDER.
  93.             Text string is clipped to fit inside the button via the
  94.             TextLength() function. The text string may contain varargs
  95.             format specifiers compatible to RawDoFmt() if the varargs data
  96.             is supplied via BUTTON_VarArgs.
  97.  
  98.             Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  99.  
  100.         GA_Image (struct Image *)
  101.             Used to specify the image to use for the label of the gadget.
  102.             The DrawImageState() function is used to draw the image.
  103.             Changing the label will invoke GM_RENDER.
  104.  
  105.             Defaults to NULL.
  106.  
  107.             Applicability is (OM_NEW, OM_SET)
  108.  
  109.         GA_SelectImage (struct Image *)
  110.             Used to specify the image to use for the label of the gadget
  111.             in the selected state. The DrawImageState() function is used
  112.             to draw the image. Changing the label will invoke GM_RENDER
  113.             if the gadget is currently selected.
  114.  
  115.             Defaults to NULL.
  116.  
  117.             Applicability is (OM_NEW, OM_SET)
  118.  
  119.         GA_TextAttr (struct TextAttr *)
  120.             Text attribute for the font to use for the text labels.
  121.  
  122.             Defaults to RPort->Font, which is often the screen or
  123.             window preferences font.
  124.  
  125.             Applicability is (OM_NEW, OM_SET)
  126.  
  127.         GA_ReadOnly (BOOL)
  128.             Read-only gadgets ignore activation attempts.
  129.  
  130.             Defaults to FALSE.
  131.  
  132.             Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  133.  
  134.         BUTTON_AutoButton (UWORD)
  135.             Used to create automatic button with one of the selected
  136.             scaled image glyphs. Accepted settings are;
  137.  
  138.                 BAG_POPFILE        - popup file selection glyph
  139.                 BAG_POPDRAWER   - popup drawer selection glyph
  140.                 BAG_POPFONT        - popup font selection glyph
  141.                 BAG_CHECKBOX    - checkmark glyph (same as checkbox.gadget)
  142.                 BAG_CANCELBOX   - NOT IMPLEMENETED!
  143.                 BAG_UPARROW        - up arrow
  144.                 BAG_DNARROW        - down arrow
  145.                 BAG_RTARROW        - right arrow
  146.                 BAG_LFARROW        - left arrow
  147.                 BAG_POPTIME        - popup time glyph
  148.                 BAG_POPSCREEN   - popup screen mode glyph
  149.  
  150.             Defaults to 0.
  151.  
  152.             Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  153.  
  154.         BUTTON_PushButton (BOOL)
  155.             Used to indicate that the button stays pressed in when the
  156.             user selects it with the mouse.  The button may
  157.             programmatically be deselected using {GA_Selected, FALSE}.
  158.  
  159.             Defaults to FALSE.
  160.  
  161.             Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  162.  
  163.         BUTTON_TextPen (LONG)
  164.             Indicate the pen number used to render the IDS_NORMAL text.
  165.             If ~0 is specified, then TEXTPEN is used.
  166.  
  167.             Defaults to ~0.
  168.  
  169.             Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  170.  
  171.         BUTTON_BackgroundPen (LONG)
  172.             Indicate the pen number used to render the IDS_NORMAL
  173.             background.  If ~0 is specified, then BACKGROUNDPEN
  174.             is used.
  175.  
  176.             Defaults to ~0.
  177.  
  178.             Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  179.  
  180.         BUTTON_FillTextPen (LONG)
  181.             Indicate the pen number used to render the IDS_SELECTED text.
  182.             If ~0 is specified, then FILLTEXTPEN is used.
  183.  
  184.             Defaults to ~0.
  185.  
  186.             Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  187.  
  188.         BUTTON_FillPen (LONG)
  189.             Indicate the pen number used to render the IDS_SELECTED
  190.             background.  If ~0 is specified, then FILLPEN is used.
  191.  
  192.             Defaults to ~0.
  193.  
  194.             Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  195.  
  196.         BUTTON_BevelStyle (WORD)
  197.             Button bevel box rendering style, passed to bevel.image.
  198.             Supports:
  199.  
  200.                 BVS_NONE
  201.                 BVS_THIN
  202.                 BVS_BUTTON
  203.                 BVS_GROUP
  204.  
  205.             Defaults to BVS_BUTTON.
  206.  
  207.             Applicability is (OM_NEW, OM_SET)
  208.  
  209.         BUTTON_Transparent (BOOL)
  210.             Make button background rendering transparent.
  211.             EraseRect() is used rather than RectFill() so that
  212.             custom backfill rendering hooks maybe utilized.
  213.  
  214.             Defaults to FALSE.
  215.  
  216.             Applicability is (OM_NEW, OM_SET)
  217.  
  218.         BUTTON_Justification    (WORD)
  219.             Justification mode of button text label.
  220.             Supports:
  221.  
  222.                 BCJ_LEFT
  223.                 BCJ_CENTER
  224.                 BCJ_RIGHT
  225.  
  226.             Defaults to BJ_CENTER.
  227.  
  228.             Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  229.  
  230.         BUTTON_SoftStyle (WORD)
  231.             Set the GA_TextAttr font's softstyle, ie BOLD, ITALICS, etc.
  232.             See <graphics/text.h> SoftStyle definitions.
  233.  
  234.             Defaults to 0.
  235.  
  236.             Applicability is (OM_NEW, OM_SET)
  237.  
  238.         BUTTON_VarArgs (APTR)
  239.             Varargs data array to supply data for RawDoFmt() when
  240.             format specifiers are to be used in GA_Text text strings.
  241.             The internal VarArgs result buffer is presently fixed at
  242.             a maximum of 128 bytes, take care not to exceed this buffer.
  243.  
  244.             Defaults to NULL.
  245.  
  246.             Applicability is (OM_NEW, OM_SET)
  247.  
  248.         BUTTON_DomainString (STRPTR)
  249.             Used to specify the NULL terminated string to use as the text
  250.             to domain the gadgets minimum size. This string is NEVER
  251.             rendered on screen. This is useful when you need to create
  252.             a button with a empty ("") or NULL string, but want to enforce
  253.             minimum size in a layout group based on some initializing
  254.             string and the current preferenced font, rather some fixed
  255.             pixel or weighted minimum.  Added by request.
  256.  
  257.             Defaults to NULL.
  258.  
  259.             Applicability is (OM_NEW, OM_SET)
  260.             
  261.         BUTTON_Integer (int)  (V42)
  262.             Set an integer value to display a numeric string. Highly useful
  263.             for interconnect notifications from sliders, scrollers, etc.
  264.             Added by request.
  265.  
  266.             Applicability is (OM_NEW, OM_SET, OM_UPDATE)
  267.  
  268.         BUTTON_BitMap (struct BitMap *)  (V42)
  269.             Specify a BitMap to render in button, rather than image or
  270.             text. Added by request, but use of bitmap.image is highly
  271.             recommended for AmigaOS V39 and later.
  272.  
  273.             Defaults to NULL.
  274.  
  275.             Applicability is (OM_NEW, OM_SET)
  276.  
  277.         BUTTON_AnimButton (BOOL)  (V42)
  278.             Is button animatable?  Use to turn animating on or off.
  279.        
  280.             Defaults to FALSE.
  281.  
  282.             Applicability is (OM_NEW, OM_SET)
  283.  
  284.         BUTTON_AnimImages (struct Image *)  (V42)
  285.             Sets an array of struct Images for animation
  286.  
  287.             Defaults to NULL.
  288.  
  289.             Applicability is (OM_NEW, OM_SET)
  290.        
  291.         BUTTON_SelAnimImages (struct Image *)  (V42)
  292.             Sets an array of alternate images for a selected state
  293.             if used, must contain an equal number of images as the
  294.             array used for BUTTON_AnimImages.  It's wise to use the
  295.             same sized images too
  296.        
  297.             Defaults to NULL.
  298.  
  299.             Applicability is (OM_NEW, OM_SET)
  300.  
  301.         BUTTON_MaxAnimImages (LONG)  (V42)
  302.             Number of images available in the arrays
  303.        
  304.             Defaults to 0.
  305.  
  306.             Applicability is (OM_NEW, OM_SET)
  307.  
  308.         BUTTON_AnimImageNumber (LONG)  (V42)
  309.             Current image number in the array(s) to use the range of
  310.             available frames is 0 .. MaxAnimImages-1
  311.        
  312.             Defaults to 0.
  313.  
  314.             Applicability is (OM_NEW, OM_SET)
  315.  
  316.         BUTTON_AddAnimImageNumber (ULONG)  (V42)
  317.            Value to be added to the current image number counter
  318.            the counter will wrap around at MaxAnimImages
  319.        
  320.             Applicability is (OM_SET, OM_UPDATE)
  321.        
  322.         BUTTON_SubAnimImageNumber (ULONG)  (V42)
  323.             Value to be subtracted from the current image number counter
  324.             the counter will wrap around when less than 0
  325.  
  326.             Applicability is (OM_SET, OM_UPDATE)
  327.        
  328.     BUGS
  329.         Unfortunetly, this class shares the same filename and tag range
  330.         as the button gadget released by David Junod of C=, released in
  331.         the GI1.lha V42 beta archive on BIX, and later the AT DevCD.
  332.         We admit it, we screwed up... but its not a majorly serious issue
  333.         as this class is atleast 90% compatible.
  334.  
  335.         A few rarely, possibly never, used tags of the original are NOT
  336.         currently supported. The usage of BUTTON_PushButton in ReAction is
  337.         not totally compatible to Junod's. Ours acts like GA_ToggleSelect
  338.         of Junod's.
  339.         
  340.         Please report any incompatibilities immediatly.
  341. button_gc/BUTTON_GetClass                           button_gc/BUTTON_GetClass
  342.  
  343.     NAME
  344.         BUTTON_GetClass -- Gets the pointer to the button class.
  345.  
  346.     SYNOPSIS
  347.         button_class = BUTTON_GetClass();
  348.         D0
  349.  
  350.         Class * BUTTON_GetClass(VOID);
  351.  
  352.     FUNCTION
  353.         This function is only available in runtime linked version of the
  354.         class, and is not in the compiler linker library button_gc.lib.
  355.  
  356.         Obtains the pointer to the Button gadget class for use with
  357.         NewObject().  This function always returns a valid pointer so
  358.         you do not need to check it.  The reason is that if the library
  359.         opens fine, then the pointer returned is already setup.  (Of course
  360.         this implies that if opening the library fails, you shouldn't be
  361.         calling this.)
  362.  
  363.         Note that this function does not create the class, that is done
  364.         when the class library is opened.
  365.  
  366.     INPUTS
  367.         Nothing.
  368.  
  369.     RESULT
  370.         button_class - Pointer to the Button gadget class.
  371.  
  372.     SEE ALSO
  373.